Sending WhatsApp Messages

This section describes how to send messages via WhatsApp using the Sinch India Conversation API.

note

Customer opt-in is essential before sending any messages. Businesses can only initiate a new conversation with a defined, approved WhatsApp template.

Supported Message Types

Text Message
Media Message (Image, Video, Document, Audio)
Location Message
Interactive Quick Reply Button Message
Interactive List Message
Product Catalogue Message (Single & Multi-Product)
Templated Message

3.2.1.1 Text Message

Attribute	Required	Data Type	Details
`text_message`	Yes	Object	Specifies the message type as a text message
`text`	Yes	String	The text to be sent

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "91931XXXXXXX"
        }
      ]
    }
  },
  "message": {
    "text_message": {
      "text": "Today is 19/04/2023."
    }
  }
}

3.2.1.2 Media Message

A message containing a media component such as an image, document, or video. Uses the media_message object.

Attribute	Description
`url` (required)	URL to the media file
`caption`	Caption for the media on supported channels

Image Message

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91XXXXXXXXXX" }] } },
  "message": { "media_message": { "url": "https://example.com/image.jpg" } }
}

Video Message

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91XXXXXXXXXX" }] } },
  "message": { "media_message": { "url": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4" } }
}

Document Message

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91XXXXXXXXXX" }] } },
  "message": { "media_message": { "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } }
}

Audio Message

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91XXXXXXXXXX" }] } },
  "message": { "media_message": { "url": "https://sample-videos.com/audio/mp3/crowd-cheering.mp3" } }
}

3.2.1.3 Location Message

Attribute	Description
`title` (required)	Shown near the button or link that leads to a map
`label`	Label or name for the position
`coordinates.latitude` (required)	The latitude
`coordinates.longitude` (required)	The longitude

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91931XXXXXXX" }] } },
  "message": {
    "location_message": {
      "title": "Your ride is here!",
      "label": "Meet your driver at the specified address.",
      "coordinates": { "latitude": 55.610479, "longitude": 13.002873 }
    }
  }
}

3.2.1.4 Quick Reply Button Message

Uses the card_message object.

Object	Description
`choices`	Array of choice objects (max 10)
`description`	Optional description displayed below the title
`height`	Card size: `UNSPECIFIED_HEIGHT`, `SHORT`, `MEDIUM`, `TALL`
`media_message`	Optional image media component
`title`	Title of the card message

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91931XXXXXXX" }] } },
  "message": {
    "card_message": {
      "title": "Sign up for our newsletter",
      "description": "Our weekly newsletter with deals and extra content!",
      "media_message": { "url": "https://example.com/banner.png" },
      "choices": [{ "text_message": { "text": "Sign up here" } }]
    }
  }
}

3.2.1.5 List Message

Object	Required	Description
`title`	Yes	Title displayed near the products or choices
`sections`	Yes	Array of ListSection objects
`description`	No	Optional message description
`message_properties`	No	Required for product list messages

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "917764863625" }] } },
  "message": {
    "list_message": {
      "title": "Choose your ice cream flavor",
      "description": "The best ice cream in town!",
      "sections": [
        { "title": "Fruit flavors", "items": [{ "choice": { "title": "Strawberry", "postback_data": "Strawberry postback" } }, { "choice": { "title": "Blueberry", "postback_data": "Blueberry postback" } }] },
        { "title": "Other flavors", "items": [{ "choice": { "title": "Chocolate", "postback_data": "Chocolate postback" } }, { "choice": { "title": "Vanilla", "postback_data": "Vanilla postback" } }] }
      ],
      "message_properties": { "menu": "Menu" }
    }
  }
}

3.2.1.6 Product Catalogue Message

Uses the list_message object with product items:

{
  "app_id": "01E9AHW7C686SN0HZ595BH1YYY",
  "recipient": { "identified_by": { "channel_identities": [{ "channel": "WHATSAPP", "identity": "91931XXXXXXX" }] } },
  "message": {
    "list_message": {
      "title": "Title for the list message with products",
      "sections": [{ "title": "Facebook product catalog item set name", "items": [{ "product": { "id": "retailer_id_1", "marketplace": "FACEBOOK" } }, { "product": { "id": "retailer_id_2", "marketplace": "FACEBOOK" } }] }],
      "message_properties": { "catalog_id": "catalog_id" }
    }
  }
}

3.2.1.7 Templated Message

Sending a message outside a 24-hour customer care session requires an approved template. All marketing, utility, or authentication conversations must start with user opt-in.

The channel_template object for WhatsApp:

Attribute	Required	Description
`template_id`	Yes	The ID of the template
`version`	Yes	Template version to use
`language_code`	No	BCP-47 language code
`parameters`	No	Concrete values for all template variables

Parameter Key Format

<component_type>[<component_index>]<component_sub_type>[<parameter_index>]<parameter_field>

component_type: header, body, or button
component_index: 0-based index (for button components only)
component_sub_type: quick_reply or url (for button components only)
parameter_index: 1-based index
parameter_field: text, payload, document., image., or video.*

Case 1 — Text Template

{ "message": { "template_message": { "channel_template": { "WHATSAPP": { "template_id": "text_template", "language_code": "en", "parameters": { "body[1]text": "Value of first parameter", "body[2]text": "Value of second parameter" } } } } } }

Case 2 — Image Template

{ "message": { "template_message": { "channel_template": { "WHATSAPP": { "template_id": "text_template", "language_code": "en", "parameters": { "header[1]image.link": "https://example.com/image.jpg", "body[1]text": "Value of first parameter" } } } } } }

Case 3 — Video Template

{ "message": { "template_message": { "channel_template": { "WHATSAPP": { "template_id": "text_template", "language_code": "en", "parameters": { "header[1]video.link": "https://example.com/video.mp4", "body[1]text": "Value of first parameter" } } } } } }

Case 4 — Document Template

{ "message": { "template_message": { "channel_template": { "WHATSAPP": { "template_id": "text_template", "language_code": "en", "parameters": { "header[1]document.link": "https://example.com/document.pdf", "header[1]document.filename": "document.pdf", "body[1]text": "Value of first parameter" } } } } } }

Case 5 — Location Template

Parameter Field Key	Description	Required
`header[1]location.longitude`	Longitude	Yes
`header[1]location.latitude`	Latitude	Yes
`header[1]location.name`	Name of the location	No
`header[1]location.address`	Address	No

Case 7 — Interactive (Buttons) Template

Parameter Field Key	Description	Required
`button[n]url[1]text`	Dynamic URL suffix for URL button	Yes, if URL button
`button[m]quick_reply[1]payload`	Postback payload	Yes, if quick reply button

Quick Reply:

{ "parameters": { "body[1]text": "Value", "button[0]quick_reply[1]payload": "button0clicked", "button[1]quick_reply[1]payload": "button1clicked" } }

Call-to-Action:

{ "parameters": { "body[1]text": "Value", "button[0]url[1]text": "Value for URL suffix button 1" } }

Supported Message Types​

3.2.1.1 Text Message​

3.2.1.2 Media Message​

3.2.1.3 Location Message​

3.2.1.4 Quick Reply Button Message​

3.2.1.5 List Message​

3.2.1.6 Product Catalogue Message​

3.2.1.7 Templated Message​

Parameter Key Format​

Case 1 — Text Template​

Case 2 — Image Template​

Case 3 — Video Template​

Case 4 — Document Template​

Case 5 — Location Template​

Case 7 — Interactive (Buttons) Template​